home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / util / cli / Man3714.lha / Man / Man.doc < prev    next >
Encoding:
Text File  |  1995-03-31  |  10.8 KB  |  423 lines
  1.  
  2.  MAN, written by Kai Iske February 28. 1994
  3.       This is PUBLIC DOMAIN; you may do with it whatever you like
  4.  
  5.  
  6. If you change/republish/delete/sell the program or do anything similar, please
  7. be so kind to keep my name within the program and all the other files, even
  8. though you`re not obliged to, as for the definition of Public Domain
  9.  
  10. MAN  was  written  because  of  the fact that MRMan (by Mark Rinfret) had some
  11. severe  problems  under  OS 2.x (or was it 3.x).  Anyway, I wrote this tool in
  12. order not to have to keep in mind the locations of all the various man pages I
  13. spread across the subdirectories of my MAN: directory.
  14.  
  15. MAN was written using SAS 6.51....
  16.  
  17.  
  18.  
  19.  
  20. ----- NOTE WSHELL USERS -----
  21.  
  22. If you are using WShell, I strongly recommend that you call/set up your CNC:
  23. handler using the following option, otherwise MAN won`t be able to call your
  24. specified viewer(s)
  25.  
  26.  DHOpts CNC:0/11/640/200//brkmode#2
  27.  
  28. Even better is to set this as default when installing WShell. The critical
  29. part is the "brkmode#2" parameter. This one *MUST* be set. This is not a bug
  30. in Man, rather than a misbehaviour of WShell which will get confused when
  31. calling SystemTags() without if you haven`t set this option.
  32.  
  33.  
  34. (Thanks to Ralph Babel for pointing this out)
  35.  
  36. ----- NOTE WSHELL USERS -----
  37.  
  38.  
  39.  
  40.  
  41. !!! Man requires OS 2.x and up to run !!!
  42.  
  43.  
  44.  
  45. -----------------
  46. What does MAN ???
  47. -----------------
  48.  
  49.  
  50. Well, it is a MAN command similar to the one found on any UNIX System.  Simply
  51. type  "man dummy" and the manual pages (documentation) for a file called dummy
  52. will  be searched for.  If man was successful in finding the appropriate file,
  53. a textviewer will be used to display the documentation.
  54.  
  55. You may configure MAN in order to tell the program where to find the man pages
  56. and  what  text  viewers  to  use.   Wait a minute.  Textviewers ???  Yep, MAN
  57. recognizes the following suffixes as to be part of man pages:
  58.  
  59.   .doc   - Simple ASCII text file
  60.   .man   - Simple ASCII text file
  61.   .guide - Got it, AmigaGuide compatible guide file.
  62.   .dvi   - Whoops, TeX .DVI output
  63.  
  64. So now you know why there are different textviewers.
  65.  
  66.    For example...
  67.  
  68.       You have the documentation for a program called "KCommodity" somewhere
  69.       within your docs directory. The doc file is called "KCommodity.Man". In
  70.       order to get the documentation loaded by man, simply type:
  71.  
  72.           MAN KCommodity
  73.  
  74.       ...and the ASCII textviewer will be used. If your filename ends up with
  75.       .guide ("KCommodity.guide"), MAN assumes it to be a GUIDE file and will
  76.       use the GUIDE Viewer instead...
  77.  
  78.       See, no suffixes needed. MAN will take the first file matching a
  79.       suffix mentioned above.
  80.  
  81.  
  82. You may even add features to MAN using environment variables. Read on...
  83.  
  84.  
  85. ----------------------
  86. How to install MAN ???
  87. ----------------------
  88.  
  89. Copy the main program to a directory within your search path (i.e. C:).
  90.  
  91. Simply set an environment variable, so that MAN knows what to do.
  92. The template for this variable (MANOPT) is as follows:
  93.  
  94.    MANPATHS/K/A,MANVIEW/K/A,MANVIEWAG/K/A,MANVIEWDVI/K/A,MANNRMEXT/K,MANAGEXT/K,
  95.    MANDVIEXT/K,MANNOVIEW/K,MANGETFILE/S,MANBASENAME/S
  96.  
  97.  
  98.   *REMEMBER* to enclose parameters containing spaces by quotes. If you don`t
  99. want to write a file MANOPT to your ENVARC: directory but like to use SetEnv
  100. from within your S:User-StartUp file, use something like this :
  101.  
  102.  
  103.   SetEnv MANOPT "... MANVIEWAG=*"SYS:Utilities/AmigaGuide PUBSCREEN 'Dummy'*""
  104.  
  105. The ellipsis "..." is only meant to shorten the example, of course you have
  106. to add the other (needed) parameters as well. You see, if you want to set a
  107. variable to a string which contains spaces you have to use the special
  108. escape charater *" to force quotes.
  109.  
  110. Required parameters are : MANPATHS, MANVIEW, MANVIEWAG, and MANVIEWDVI
  111.  
  112.  
  113.                              --------------------
  114.  
  115.  
  116. The meaning of the keywords :
  117.  
  118.    MANPATHS    - This option tells man where to look for man pages.
  119.  
  120.    For example...
  121.  
  122.       MANPATHS=MAN:,MAN:CSHDOC|MAN:HPDOCS,MAN:AUTODOCS
  123.  
  124.    You see, you may either use "," or the "|" as seperators between
  125.    directory names.
  126.  
  127.  
  128.  
  129.  
  130.    MANVIEW     - This one is the path (including filename) for the
  131.                  textviewer you wish to use for displaying normal
  132.                  ASCII files.
  133.  
  134.    For example...
  135.  
  136.       MANVIEW=SYS:Utilities/More
  137.  
  138.    REMEMBER: Complete path and filename
  139.  
  140.  
  141.  
  142.  
  143.  
  144.    MANVIEWAG   - This one is used to set the path (and filename) for
  145.                  the AmigaGuide GUIDE-Viewer.
  146.  
  147.    For example...
  148.  
  149.       MANVIEWAG=SYS:Utilities/AmigaGuide
  150.  
  151.    REMEMBER : Complete path and filename
  152.  
  153.  
  154.  
  155.  
  156.    MANVIEWDVI  - This one is used to set the path (and filename) for
  157.                  the DVI-Viewer.
  158.  
  159.    For example...
  160.  
  161.       MANVIEWDVI=TeX:bin/ShowDVI
  162.  
  163.    REMEMBER : Complete path and filename
  164.  
  165.  
  166.  
  167.  
  168.  
  169. Additionally there are six more keywords you may use to add
  170. extensions and functions to man. These are :
  171.  
  172.    MANNRMEXT   - You may use this option to add extensions to the already
  173.                  known, which should be treated (shown) as plain ASCII files.
  174.  
  175.    For example...
  176.  
  177.       MANNRMEXT=.txt|.asc|.dok
  178.  
  179.    Will add these extensions to known ASCII files
  180.  
  181.  
  182.  
  183.  
  184.    MANAGEXT    - Using this option you may add extensions for AmigaGuide
  185.                  files
  186.  
  187.    For example
  188.  
  189.       MANAGEXT=.bla|.blo|.blu
  190.  
  191.    Will add these extensions to known AmigaGuide compatible files
  192.  
  193.  
  194.  
  195.  
  196.    MANDVIEXT   - Using this option you may add extensions for DVI
  197.                  files
  198.  
  199.    For example
  200.  
  201.       MANDVIEXT=.ble|.bli
  202.  
  203.    Will add these extensions to known DVI compatible files
  204.  
  205.  
  206.  
  207.  
  208.    MANNOVIEW   - If a file doesn`t end up with an extension (starting with a
  209.                  dot), MAN will use the predefined ASCII viewer to display
  210.                  such a file. You may change the viewer for such files using
  211.                  this option. Additionally this option may be turned off,
  212.                  when you issue "NONE".
  213.  
  214.    For example
  215.  
  216.       MANNOVIEW=SYS:Utilities/AmigaGuide
  217.  
  218.    Will tell MAN to display files, without extension, using AmigaGuide
  219.  
  220.  
  221.  
  222.  
  223.    MANGETFILE  - If MAN didn`t succeed in finding the required man page
  224.                  it will pop up a FileRequester asking for a file to
  225.                  be loaded. The requester will pop up if you didn`t
  226.                  specify any manpage, too. In this case MAN won`t
  227.                  issue an error, but it will if you omit this keyword.
  228.  
  229.                  Simply add this option to your MANOPT environment var,
  230.                  if you want MAN to pop up a FileRequester.
  231.  
  232.  
  233.  
  234.  
  235.    MANBASENAME - Normally you would call MAN with only a filename/manpage,
  236.                  but if you launch MAN from within (ie) ToolsDaemon, it might
  237.                  be launched with a pathname as well. The pathpart of a
  238.                  manpage will be cut off if you supply this attribute
  239.                  to MANOPT.
  240.  
  241.  
  242.    MANLOCAL    - Causes MAN to search the current directory first.
  243.  
  244.  
  245.  
  246. A more complete example
  247.  
  248.  
  249.    SetEnv MANOPT "MANPATHS=docs:|guide: MANVIEW=More MANVIEWAG=AmigaGuide
  250.              MANVIEWDVI=ShowDVI"
  251.  
  252.  
  253.  
  254. It is best to place this line within your S:User-StartUp file, or simply edit
  255. a file called MANOPT in your ENVARC: directory containing the parameters. Then
  256. copy the file to ENV:, or simply reboot.
  257.  
  258.  
  259.  
  260. The ARexx-Script "ToolManagerMan.rexx" may be used from within ToolManager
  261. Dock-Windows. If run, it will open a requester using "rexxreqtools.library"
  262. asking for the man-page you want to view. The ARexx Script requires
  263. rexxreqtools.library and reqtools.library. It was written by Franz S. Borgerding
  264.  
  265.  
  266.                              --------------------
  267.  
  268.  
  269.  
  270. -----------
  271. Version 1.0
  272. -----------
  273.   - initial release
  274.  
  275.  
  276. -----------
  277. Version 1.1
  278. -----------
  279.   - Accidentially called Exit() instead of exit(), which
  280.     prevented the program to pass the cleanup code of SAS.
  281.     So a lock to the directory was kept and the shell could
  282.     never been left.............
  283.  
  284.  
  285. -----------
  286. Version 1.2
  287. -----------
  288.   - Used MAN as a keyword for the template which prevented MAN
  289.     to accept inputs like "man man".
  290.  
  291.  
  292. -----------
  293. Version 1.3
  294. -----------
  295.   - Added CTRL-C checking
  296.   - Recompiled using SAS 6.50
  297.   - Reduced stack usage
  298.   - Reduced executable size
  299.  
  300.  
  301. -----------
  302. Version 1.4
  303. -----------
  304.   - DOS-Library wasn`t closed
  305.  
  306.  
  307. -----------
  308. Version 1.5
  309. -----------
  310.   - Referenced free memory area
  311.  
  312.  
  313. -----------
  314. Version 1.6
  315. -----------
  316.   - Added MANRMEXT, MANAGEXT and MANNOVIEW options,
  317.     which may be used for extensibility of MAN
  318.     (Somehow suggested by : Michael 'Mick' Hohmann)
  319.  
  320.  
  321. -----------
  322. Version 1.7
  323. -----------
  324.   - All config variables have been moved to a single one,
  325.     which will be parsed just like a CommandLine
  326.     (Suggested by : Michael 'Mick' Hohmann)
  327.  
  328.  
  329. -----------
  330. Version 1.8
  331. -----------
  332.   - Man now correctly handles multi-assigns, since ExAll
  333.     doesn`t....;)
  334.     (Reported by : Jan Hoeydahl)
  335.  
  336.  
  337. -----------
  338. Version 1.9
  339. -----------
  340.   - Recompiled using SAS/C 6.51
  341.   - Added MANGETFILE parameter
  342.     (Requested by : Bill Hogsett)
  343.  
  344.  
  345. ------------
  346. Version 1.10
  347. ------------
  348.   - Mike Barsoom added MANBASENAME attribute for stripping
  349.     off any path names from the manpage name. Useful when
  350.     launching MAN from within (ie) ToolsDaemon
  351.     (Submitted by : Mike Barsoom)
  352.  
  353.  
  354. ------------
  355. Version 1.11
  356. ------------
  357.   - Man will no longer issue an error if you a) didn`t specify a
  358.     manpage and b) set the MANGETFILE attribute for the File
  359.     Requester. This way the Requester will popup if you
  360.     call MAN without any arguments
  361.     (Requested by : Bill Hogsett)
  362.   - The FileRequester will pop up on the default PubScreen now
  363.     (Requested by : Bill Hogsett)
  364.   - The default path for the FileRequester will be set to the
  365.     first Dir of the MANPATHS now
  366.     (Requested by : Bill Hogsett)
  367.   - Support for DVI files added
  368.   - MAN will set the Viewer`s current dir of that where the
  369.     man page resides in
  370.  
  371.  
  372. -------------
  373. Version 1.11a
  374. -------------
  375.   - Man produced an enforcer hit when no manpage was supplied
  376.     (Reported by : Michael van Elst)
  377.  
  378.  
  379. ------------
  380. Version 1.12
  381. ------------
  382.   - WShell`s incompatibility to SystemTags() forced me to use
  383.     RunCommand() for launching the external viewer
  384.     (Suggested/Reported by : Ralph Babel + Ralph Schmidt)
  385.  
  386.  
  387. ------------
  388. Version 1.13
  389. ------------
  390.   - Added new switch "MANLOCAL". This will cause
  391.     Man to search the current directory before any other
  392.     (Requested by : Mark Rose)
  393.   - Added ARexx-Script which allows the usage of Man
  394.     from within eg. ToolManager.
  395.     (written by : Franz S. Borgerding)
  396.  
  397.  
  398. -------------
  399. Version 37.14
  400. -------------
  401.   - Fixed bug in calling the programs which return a code
  402.     unequal to zero
  403.   - Changed version numbering to official scheme
  404.  
  405.  
  406. Hope you like it, if not, delete it......
  407.  
  408.  
  409.  
  410. So long,
  411.  
  412.      Kai
  413.  
  414.  
  415.  
  416.  
  417.  --- Kai Iske
  418.  Brucknerstrasse 18, 63452 Hanau, Germany, Tel.: +49-(0)6181-850181
  419.  Z-Net     : KAI@SWEET.RHEIN-MAIN.DE  Fido: Kai Iske, 2:244/6302.11
  420.  internet  : iske@informatik.uni-frankfurt.de             IRC:kiske
  421.                    CompuServe: Kai Iske, 100524,1201
  422.  ---- Life sucks ----
  423.